Sphinx で作成したドキュメントをFlaskで公開する
Sphinx はドキュメントをHTMLフォーマットで簡単に整形することができます。
code: bash
$ mkdir docs
$ sphinx-quickstart docs
$ SPHINX_DOCROOT_DIR=(cd docs; pwd)
ソースと整形後のドキュメントを別ディレクトリにした場合、通常であれば
${SPHINX_DOCROOT_DIR}/build/html 以下に作成されます。
Flaskで公開する場合は次のようにすると簡単です。
code: python
import os
from flask import Flask, send_from_directory
basedir = os.path.abspath(os.path.dirname(__file__))
app = Flask(__name__, static_folder='static')
@app.route('/favicon.ico', defaults ={"path": "favicon.ico"})
@app.route('/docs/', defaults = {"path": "index.html"})
@app.route('/docs/<path>')
@app.route('/docs/<dir>/<path>')
def web_docs(dir='', path='index.html'):
docroot = f"{basedir}/static/html/{dir}"
return send_from_directory(docroot, path)
if __name__ == "__main__":
app.run(
host=os.getenv("APP_HOST", "localhost"),
port=os.getenv("APP_PORT", 8080),
threaded=True,
)
code: bash
$ mkdir static
$ cd static
$ ln -s "${SPHINX_DOCROOT_DIR}/build/html" html
code: bash
$ cd static
$ unzip $HOME/favicon.zip
$ cp favicon.ico html/
Flaskのアプリケーションを追加するのであれば、必要に応じてテンプレートを用意します。
code: htnml
{% block doc -%}
<!DOCTYPE html>
<html{% block html_attribs %}{% endblock html_attribs %}>
{%- block html %}
<head>
{%- block head %}
<title>{% block title %}{% endblock title %}</title>
{%- block metas %}
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta charset="UTF-8">
{%- endblock metas %}
{%- block favicon %}
<link rel="apple-touch-icon" sizes="180x180"
href="/static/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32"
href="/static/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16"
href="/static/favicon-16x16.png">
<link rel="manifest" href="/static/site.webmanifest">
{%- endblock favicon %}
{%- block styles %}
{%- endblock styles %}
{%- endblock head %}
</head>
<body{% block body_attribs %}{% endblock body_attribs %}>
{%- block body %}
{%- block contents %}
{%- endblock contents %}
{%- block footer %}
{%- endblock footer %}
{%- block scripts %}
{%- endblock scripts %}
{%- endblock body %}
</body>
{%- endblock html %}
</html>
{% endblock doc -%}
経緯
sphinx が生成するファイルには次のようにファイル参照が散在しています。
デフォルトでは、_static、 _template、_images などとなります。
code: html
:
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
:
Flask で管理する静的ファイルは Flask()のインスタンスを初期化するときに、
static_folder に静的ファイルを格納するディレクトリへの相対パスを与えます。
アプリケーションと Sphinx ドキュメントの共存がはじめはうまくいかず、
スタイルシートやスクリプトをうまく読み込むことができませんでした。
そこで、今後同じことで悩みたくなかったのできっちりと動作するような設定を確認し、
備忘録として残すことにしました。